home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1997 April: Mac OS SDK / Dev.CD Apr 97 SDK1.toast / Development Kits (Disc 1) / Interfaces&Libraries / Interfaces / CIncludes / SoundSprocket.h < prev    next >
Encoding:
C/C++ Source or Header  |  1996-09-11  |  14.6 KB  |  486 lines  |  [TEXT/MPS ]
  1. /*
  2.      File:        SoundSprocket.h
  3.  
  4.      Contains:    Public interfaces for SoundSprocket
  5.  
  6.      Version:    Technology:    Apple Game Sprockets 1.0
  7.                  Package:    Universal Interfaces 2.1.4
  8.  
  9.      Copyright:    © 1984-1996 by Apple Computer, Inc.
  10.                  All rights reserved.
  11.  
  12.      Bugs?:        If you find a problem with this file, use the Apple Bug Reporter
  13.                  stack.  Include the file and version information (from above)
  14.                  in the problem description and send to:
  15.                      Internet:    apple.bugs@applelink.apple.com
  16.                      AppleLink:    APPLE.BUGS
  17. */
  18.  
  19. #ifndef __SOUNDSPROCKET__
  20. #define __SOUNDSPROCKET__
  21.  
  22. #ifndef __TYPES__
  23. #include <Types.h>
  24. #endif
  25.  
  26. /*    #include <ConditionalMacros.h>                                */
  27.  
  28. #ifndef __EVENTS__
  29. #include <Events.h>
  30. #endif
  31.  
  32. #ifndef QD3D_h
  33. #include <QD3D.h>
  34. #endif
  35.  
  36. #ifndef QD3DCamera_h
  37. #include <QD3DCamera.h>
  38. #endif
  39.  
  40.  
  41. #if GENERATINGPOWERPC
  42.  
  43. #ifdef __cplusplus
  44. extern "C" {
  45. #endif
  46.  
  47. #if PRAGMA_ALIGN_SUPPORTED
  48. #pragma options align=power
  49. #endif
  50.  
  51.  
  52. /*******************************************************************************
  53.  *    • TODO: This stuff will be moved to Errors.h
  54.  ******************************************************************************/
  55. enum {
  56.     kSSpInternalErr            = -30340,
  57.     kSSpVersionErr            = -30341,
  58.     kSSpCantInstallErr        = -30342,
  59.     kSSpParallelUpVectorErr    = -30343,
  60.     kSSpScaleToZeroErr        = -30344
  61. };
  62.  
  63.  
  64. /*******************************************************************************
  65.  *    This stuff has been moved to Sound.h
  66.  *
  67.  *    If it is not there in your Sound.h, get a new one.  If you can't find the
  68.  *    new one, #define __USING_OLD_SOUND_H__ 1 before you #include this file.
  69.  ******************************************************************************/
  70. #if defined(__USING_OLD_SOUND_H__) && __USING_OLD_SOUND_H__
  71.     #ifndef __SOUNDCOMPONENTS__
  72.         #include <SoundComponents.h>
  73.     #endif
  74.     
  75.     enum {
  76.         siPreMixerSoundComponent    = 'prmx',
  77.         siPostMixerSoundComponent    = 'psmx',
  78.         kSoundEffectsType            = 'snfx'
  79.     };
  80.     
  81.     struct SoundComponentLink {
  82.         ComponentDescription     description;/*Describes the sound component*/
  83.         SoundSource             mixerID;    /*Reserved by Apple*/
  84.         SoundSource *            linkID;        /*Reserved by Apple*/
  85.     };
  86.     
  87.     typedef struct SoundComponentLink SoundComponentLink;
  88.     typedef SoundComponentLink *SoundComponentLinkPtr;
  89.     
  90.     /* Our subtype within kSoundEffectsType for siPreMixerSoundComponent */
  91.     enum {
  92.         kSSpLocalizationSubType        = 'snd3'
  93.     };
  94.     
  95.     /* Selectors for SndSetInfo and SndGetInfo */
  96.     enum {
  97.         siSSpCPULoadLimit    = '3dll',        /* Parameter: UInt32, Get only            */
  98.         siSSpSpeakerSetup    = '3dst',        /* Parameter: SSpSpeakerSetupData, Set/Get*/
  99.         siSSpLocalization    = '3dif'        /* Parameter: SSpLocalizationData, Set/Get*/
  100.     };
  101. #endif
  102.  
  103.  
  104. /*******************************************************************************
  105.  *    SndSetInfo/SndGetInfo Messages
  106.  ******************************************************************************/
  107. // The siSSpCPULoadLimit = '3dll' selector for SndGetInfo fills in a value of
  108. // type UInt32.
  109.  
  110.  
  111. enum {
  112.     kSSpSpeakerKind_Stereo            = 0,
  113.     kSSpSpeakerKind_Mono            = 1,
  114.     kSSpSpeakerKind_Headphones        = 2
  115. };
  116.  
  117.  
  118. // This is the data type is used with the SndGet/SetInfo selector
  119. // siSSpSpeakerSetup = '3dst'
  120. typedef struct SSpSpeakerSetupData {
  121.     UInt32                speakerKind;    /* Speaker configuration                */
  122.     float                speakerAngle;    /* Angle formed by user and speakers    */
  123.  
  124.     UInt32                reserved0;        /* Reserved for future use -- set to 0    */
  125.     UInt32                reserved1;        /* Reserved for future use -- set to 0    */
  126. } SSpSpeakerSetupData;
  127.  
  128.  
  129. enum {
  130.     kSSpMedium_Air                = 0,
  131.     kSSpMedium_Water            = 1
  132. };
  133.  
  134.  
  135. enum {
  136.     kSSpSourceMode_Unfiltered    = 0,    /* No filtering applied                    */
  137.     kSSpSourceMode_Localized    = 1,    /* Localized by source position            */
  138.     kSSpSourceMode_Ambient        = 2,    /* Coming from all around                */
  139.     kSSpSourceMode_Binaural        = 3        /* Already binaurally localized            */
  140. };
  141.  
  142.  
  143. typedef struct SSpLocationData {
  144.     float                elevation;        /* Angle of the meridian -- pos is up    */
  145.     float                azimuth;        /* Angle of the parallel -- pos is left    */
  146.     float                distance;        /* Distance between source and listener    */
  147.     float                projectionAngle;/* Cos(angle) between cone and listener    */
  148.     float                sourceVelocity;    /* Speed of source toward the listener    */
  149.     float                listenerVelocity;/*Speed of listener toward the source    */
  150. } SSpLocationData;
  151.  
  152.  
  153. typedef struct SSpVirtualSourceData {
  154.     float                attenuation;    /* Attenuation factor                    */
  155.     SSpLocationData        location;        /* Location of virtual source            */
  156. } SSpVirtualSourceData;
  157.  
  158.  
  159. // This is the data type is used with the SndGet/SetInfo selector
  160. // siSSpLocalization = '3dif'
  161. typedef struct SSpLocalizationData {
  162.     UInt32                cpuLoad;        /* CPU load vs. quality -- 0 is best    */
  163.     
  164.     UInt32                medium;            /* Medium for sound propagation            */
  165.     float                humidity;        /* Humidity when medium is air            */
  166.     float                roomSize;        /* Reverb model -- distance bet. walls    */
  167.     float                roomReflectivity;/*Reverb model -- bounce attenuation    */
  168.     float                reverbAttenuation;/*Reverb model -- mix level            */
  169.  
  170.     UInt32                sourceMode;        /* Type of filtering to apply            */
  171.     float                referenceDistance;/*Nominal distance for recording        */
  172.     float                coneAngleCos;    /* Cos(angle/2) of attenuation cone        */
  173.     float                coneAttenuation;/* Attenuation outside the cone            */
  174.     SSpLocationData        currentLocation;/* Location of the sound                 */
  175.  
  176.     UInt32                reserved0;        /* Reserved for future use -- set to 0    */
  177.     UInt32                reserved1;        /* Reserved for future use -- set to 0    */
  178.     UInt32                reserved2;        /* Reserved for future use -- set to 0    */
  179.     UInt32                reserved3;        /* Reserved for future use -- set to 0    */
  180.  
  181.     UInt32                virtualSourceCount;/*Number of reflections                */
  182.     SSpVirtualSourceData virtualSource[4];/*The reflections                        */
  183. } SSpLocalizationData;
  184.  
  185.  
  186. typedef Boolean (*SSpEventProcPtr) (EventRecord* inEvent);
  187.  
  188.  
  189. /*******************************************************************************
  190.  *    Global functions
  191.  ******************************************************************************/
  192. OSStatus SSpConfigureSpeakerSetup(
  193.     SSpEventProcPtr                inEventProcPtr);
  194.  
  195. OSStatus SSpGetCPULoadLimit(
  196.     UInt32*                        outCPULoadLimit);
  197.  
  198.  
  199. /*******************************************************************************
  200.  *    Routines for Maniulating Listeners
  201.  ******************************************************************************/
  202. typedef struct SSpListenerPrivate*    SSpListenerReference;
  203.  
  204. OSStatus SSpListener_New(
  205.     SSpListenerReference*        outListenerReference);
  206.  
  207. OSStatus SSpListener_Dispose(
  208.     SSpListenerReference        inListenerReference);
  209.  
  210. OSStatus SSpListener_SetTransform(
  211.     SSpListenerReference        inListenerReference,
  212.     const TQ3Matrix4x4*            inTransform);
  213.  
  214. OSStatus SSpListener_GetTransform(
  215.     SSpListenerReference        inListenerReference,
  216.     TQ3Matrix4x4*                outTransform);
  217.  
  218. OSStatus SSpListener_SetPosition(
  219.     SSpListenerReference        inListenerReference,
  220.     const TQ3Point3D*            inPosition);
  221.  
  222. OSStatus SSpListener_GetPosition(
  223.     SSpListenerReference        inListenerReference,
  224.     TQ3Point3D*                    outPosition);
  225.  
  226. OSStatus SSpListener_SetOrientation(
  227.     SSpListenerReference        inListenerReference,
  228.     const TQ3Vector3D*            inOrientation);
  229.  
  230. OSStatus SSpListener_GetOrientation(
  231.     SSpListenerReference        inListenerReference,
  232.     TQ3Vector3D*                outOrientation);
  233.  
  234. OSStatus SSpListener_SetUpVector(
  235.     SSpListenerReference        inListenerReference,
  236.     const TQ3Vector3D*            inUpVector);
  237.  
  238. OSStatus SSpListener_GetUpVector(
  239.     SSpListenerReference        inListenerReference,
  240.     TQ3Vector3D*                outUpVector);
  241.  
  242. OSStatus SSpListener_SetCameraPlacement(
  243.     SSpListenerReference        inListenerReference,
  244.     const TQ3CameraPlacement*    inCameraPlacement);
  245.  
  246. OSStatus SSpListener_GetCameraPlacement(
  247.     SSpListenerReference        inListenerReference,
  248.     TQ3CameraPlacement*            outCameraPlacement);
  249.  
  250. OSStatus SSpListener_SetVelocity(
  251.     SSpListenerReference        inListenerReference,
  252.     const TQ3Vector3D*            inVelocity);
  253.  
  254. OSStatus SSpListener_GetVelocity(
  255.     SSpListenerReference        inListenerReference,
  256.     TQ3Vector3D*                outVelocity);
  257.  
  258. OSStatus SSpListener_GetActualVelocity(
  259.     SSpListenerReference        inListenerReference,
  260.     TQ3Vector3D*                outVelocity);
  261.  
  262. OSStatus SSpListener_SetMedium(
  263.     SSpListenerReference        inListenerReference,
  264.     UInt32                        inMedium,
  265.     float                        inHumidity);
  266.  
  267. OSStatus SSpListener_GetMedium(
  268.     SSpListenerReference        inListenerReference,
  269.     UInt32*                        outMedium,
  270.     float*                        outHumidity);
  271.  
  272. OSStatus SSpListener_SetReverb(
  273.     SSpListenerReference        inListenerReference,
  274.     float                        inRoomSize,
  275.     float                        inRoomReflectivity,
  276.     float                        inReverbAttenuation);
  277.  
  278. OSStatus SSpListener_GetReverb(
  279.     SSpListenerReference        inListenerReference,
  280.     float*                        outRoomSize,
  281.     float*                        outRoomReflectivity,
  282.     float*                        outReverbAttenuation);
  283.  
  284. OSStatus SSpListener_SetMetersPerUnit(
  285.     SSpListenerReference        inListenerReference,
  286.     float                        inMetersPerUnit);
  287.  
  288. OSStatus SSpListener_GetMetersPerUnit(
  289.     SSpListenerReference        inListenerReference,
  290.     float*                        outMetersPerUnit);
  291.  
  292.  
  293. /*******************************************************************************
  294.  *    Routines for Manipulating Sources
  295.  ******************************************************************************/
  296. typedef struct SSpSourcePrivate*    SSpSourceReference;
  297.  
  298. OSStatus SSpSource_New(
  299.     SSpSourceReference*            outSourceReference);
  300.  
  301. OSStatus SSpSource_Dispose(
  302.     SSpSourceReference            inSourceReference);
  303.  
  304. OSStatus SSpSource_CalcLocalization(
  305.     SSpSourceReference            inSourceReference,
  306.     SSpListenerReference        inListenerReference,
  307.     SSpLocalizationData*        out3DInfo);
  308.  
  309. OSStatus SSpSource_SetTransform(
  310.     SSpSourceReference            inSourceReference,
  311.     const TQ3Matrix4x4*            inTransform);
  312.  
  313. OSStatus SSpSource_GetTransform(
  314.     SSpSourceReference            inSourceReference,
  315.     TQ3Matrix4x4*                outTransform);
  316.  
  317. OSStatus SSpSource_SetPosition(
  318.     SSpSourceReference            inSourceReference,
  319.     const TQ3Point3D*            inPosition);
  320.  
  321. OSStatus SSpSource_GetPosition(
  322.     SSpSourceReference            inSourceReference,
  323.     TQ3Point3D*                    outPosition);
  324.  
  325. OSStatus SSpSource_SetOrientation(
  326.     SSpSourceReference            inSourceReference,
  327.     const TQ3Vector3D*            inOrientation);
  328.  
  329. OSStatus SSpSource_GetOrientation(
  330.     SSpSourceReference            inSourceReference,
  331.     TQ3Vector3D*                outOrientation);
  332.  
  333. OSStatus SSpSource_SetUpVector(
  334.     SSpSourceReference            inSourceReference,
  335.     const TQ3Vector3D*            inUpVector);
  336.  
  337. OSStatus SSpSource_GetUpVector(
  338.     SSpSourceReference            inSourceReference,
  339.     TQ3Vector3D*                outUpVector);
  340.  
  341. OSStatus SSpSource_SetCameraPlacement(
  342.     SSpSourceReference            inSourceReference,
  343.     const TQ3CameraPlacement*    inCameraPlacement);
  344.  
  345. OSStatus SSpSource_GetCameraPlacement(
  346.     SSpSourceReference            inSourceReference,
  347.     TQ3CameraPlacement*            outCameraPlacement);
  348.  
  349. OSStatus SSpSource_SetVelocity(
  350.     SSpSourceReference            inSourceReference,
  351.     const TQ3Vector3D*            inVelocity);
  352.  
  353. OSStatus SSpSource_GetVelocity(
  354.     SSpSourceReference            inSourceReference,
  355.     TQ3Vector3D*                outVelocity);
  356.  
  357. OSStatus SSpSource_GetActualVelocity(
  358.     SSpSourceReference            inSourceReference,
  359.     TQ3Vector3D*                outVelocity);
  360.  
  361. OSStatus SSpSource_SetCPULoad(
  362.     SSpSourceReference            inSourceReference,
  363.     UInt32                        inCPULoad);
  364.  
  365. OSStatus SSpSource_GetCPULoad(
  366.     SSpSourceReference            inSourceReference,
  367.     UInt32*                        outCPULoad);
  368.  
  369. OSStatus SSpSource_SetMode(
  370.     SSpSourceReference            inSourceReference,
  371.     UInt32                        inMode);
  372.  
  373. OSStatus SSpSource_GetMode(
  374.     SSpSourceReference            inSourceReference,
  375.     UInt32*                        outMode);
  376.  
  377. OSStatus SSpSource_SetReferenceDistance(
  378.     SSpSourceReference            inSourceReference,
  379.     float                        inReferenceDistance);
  380.  
  381. OSStatus SSpSource_GetReferenceDistance(
  382.     SSpSourceReference            inSourceReference,
  383.     float*                        outReferenceDistance);
  384.  
  385. OSStatus SSpSource_SetSize(
  386.     SSpSourceReference            inSourceReference,
  387.     float                        inLength,
  388.     float                        inWidth,
  389.     float                        inHeight);
  390.  
  391. OSStatus SSpSource_GetSize(
  392.     SSpSourceReference            inSourceReference,
  393.     float*                        outLength,
  394.     float*                        outWidth,
  395.     float*                        outHeight);
  396.  
  397. OSStatus SSpSource_SetAngularAttenuation(
  398.     SSpSourceReference            inSourceReference,
  399.     float                        inConeAngle,
  400.     float                        inConeAttenuation);
  401.  
  402. OSStatus SSpSource_GetAngularAttenuation(
  403.     SSpSourceReference            inSourceReference,
  404.     float*                        outConeAngle,
  405.     float*                        outConeAttenuation);
  406.  
  407.  
  408. /*******************************************************************************
  409.  *    LATE-BREAKING NEWS
  410.  *
  411.  *    After the documentation was completed, it was decided that the SSpSetup
  412.  *    were not specific enough.  We renamed them to SSpSpeakerSetup.  These
  413.  *    #defines allow code to be written per the documentation.  But please use
  414.  *    the new, longer names, as the #defines will be removed in a later release.
  415.  ******************************************************************************/
  416. #define siSSpSetup                siSSpSpeakerSetup
  417. #define SSpSetupData            SSpSpeakerSetupData
  418. #define SSpConfigureSetup        SSpConfigureSpeakerSetup
  419.  
  420.  
  421. /*******************************************************************************
  422.  *    MORE LATE-BREAKING NEWS
  423.  *
  424.  *    The SndGetInfo selector siSSpFilterVersion and datatype SSpFilterVersionData
  425.  *    have been removed in favor of an alternate way of accessing filter version
  426.  *    information.  The following function may be used for this purpose.
  427.  *******************************************************************************
  428. // **************************** GetSSpFilterVersion ****************************
  429. // Finds the manufacturer and version number of the SoundSprocket filter that
  430. // may be installed.  inManufacturer should be the manufacturer code specified
  431. // at the installation time, which may be zero to allow any manufacturer.
  432. // If no error is encountered, outManufacturer is set to the actual manufacturer
  433. // code and outMajorVersion and outMinorVersion are set to the component
  434. // specification level and manufacturer's implementation revision, respectively.
  435. OSStatus GetSSpFilterVersion(
  436.     OSType                    inManufacturer,
  437.     OSType*                    outManufacturer,
  438.     UInt32*                    outMajorVersion,
  439.     UInt32*                    outMinorVersion)
  440. {
  441.     OSStatus                err;
  442.     ComponentDescription    description;
  443.     Component                componentRef;
  444.     UInt32                    vers;
  445.     
  446.     // Set up the component description
  447.     description.componentType            = kSoundEffectsType;
  448.     description.componentSubType        = kSSpLocalizationSubType;
  449.     description.componentManufacturer    = inManufacturer;
  450.     description.componentFlags            = 0;        
  451.     description.componentFlagsMask        = 0;    
  452.     
  453.     // Find a component matching the description
  454.     componentRef = FindNextComponent(nil, &description);
  455.     if (componentRef == nil)  return couldntGetRequiredComponent;
  456.     
  457.     // Get the component description (for the manufacturer code)
  458.     err = GetComponentInfo(componentRef, &description, nil, nil, nil);
  459.     if (err != noErr)  return err;
  460.     
  461.     // Get the version composite
  462.     vers = (UInt32) GetComponentVersion((ComponentInstance) componentRef);
  463.     
  464.     // Return the results
  465.     *outManufacturer = description.componentManufacturer;
  466.     *outMajorVersion = HiWord(vers);
  467.     *outMinorVersion = LoWord(vers);
  468.     
  469.     return noErr;
  470. }
  471. *******************************************************************************/
  472.  
  473.  
  474. #ifdef __cplusplus
  475. }
  476. #endif
  477.  
  478.  
  479.  
  480. #if PRAGMA_ALIGN_SUPPORTED
  481. #pragma options align=reset
  482. #endif
  483.  
  484. #endif /* GENERATINGPOWERPC */
  485. #endif /* __SOUNDSPROCKET__ */
  486.